---
id: index
title: tctl v1.17 command reference
sidebar_label: CLI (tctl)
description: The Temporal CLI (tctl) allows seamless interaction with a Temporal Cluster, supporting Namespace and Workflow operations; it will deprecate after Temporal CLI v1.0 release.
slug: /tctl-v1
toc_max_heading_level: 4
keywords:
  - cli
  - cli reference
  - tctl
  - term
---

:::info Temporal CLI is now available

The public preview of [Temporal CLI](/cli) is now available.
We encourage you to begin using it and to provide feedback.

After the release of Temporal CLI v1.0, tctl will deprecate.

:::

:::note

This documentation reflects tctl version 1.17.

:::

The Temporal CLI (tctl) is a command-line tool that you can use to interact with a Temporal Cluster.
It can perform [Namespace](/namespaces) operations (such as register, update, and describe) and [Workflow](/workflows) operations (such as start
Workflow, show Workflow History, and Signal Workflow).

- [How to install tctl](#install)
- [Environment variables for tctl](#environment-variables)

## tctl commands

- [tctl activity](/tctl-v1/activity/)
- [tctl admin](/tctl-v1/admin/)
- [tctl batch](/tctl-v1/batch/)
- [tctl cluster](/tctl-v1/cluster/)
- [tctl dataconverter](/tctl-v1/dataconverter/)
- [tctl namespace](/tctl-v1/namespace/)
- [tctl taskqueue](/tctl-v1/taskqueue/)
- [tctl workflow](/tctl-v1/workflow/)

## How to install tctl {#install}

> The Temporal tctl documentation covers version 1.17 of the Temporal CLI.

You can install [tctl](/tctl-v1) in the following ways.

- Install locally by using [Homebrew](https://brew.sh/): `brew install tctl`
- Run locally together with Temporal Server in [Docker Compose](https://github.com/temporalio/docker-compose): `docker exec temporal-admin-tools tctl YOUR COMMANDS HERE`
  - To invoke [tctl](/tctl-v1) as though it is installed locally (such as `tctl namespace describe`), set an alias: `alias tctl="docker exec temporal-admin-tools tctl"`
- Run the [temporal-admin-tools](https://hub.docker.com/r/temporalio/admin-tools) Docker image:
  - On Linux: `docker run --rm -it --entrypoint tctl --network host --env TEMPORAL_CLI_ADDRESS=localhost:7233 temporalio/admin-tools:1.14.0`
  - On macOS or Windows: `docker run --rm -it --entrypoint tctl --env TEMPORAL_CLI_ADDRESS=host.docker.internal:7233 temporalio/admin-tools:1.14.0`
  - If your Temporal Server is running on a remote host, change the value of `TEMPORAL_CLI_ADDRESS`.
  - To simplify command lines, create a `tctl` alias.
- Install the latest version of the tctl in your `GOPATH`: `go install github.com/temporalio/tctl/cmd/tctl@latest`

**Note:** To use [tctl](/tctl-v1), you must have a Temporal Server running.

To see help for [tctl](/tctl-v1) commands, enter the following commands.

| Command             | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `tctl -h`           | Display help for top-level commands and global options        |
| `tctl namespace -h` | Display help for [Namespace](/namespaces) operations          |
| `tctl workflow -h`  | Display help for [Workflow](/workflows) operations            |
| `tctl taskqueue -h` | Display help for [Task Queue](/workers#task-queue) operations |

## Global modifiers

You can supply the values for many of these modifiers by setting [environment variables](#environment-variables) instead of including the modifiers in a tctl command.

### --address

Specify a host and port for the Frontend Service.
The default is `127.0.0.1:7233`.

### --auto_confirm

Automatically confirm all prompts.

### --context_timeout

Specify a timeout for the context of an RPC call in seconds.
The default value is 5.

### --data_converter_plugin

Specify the name of the executable for a custom Data Converter plugin.

### --headers_provider_plugin

Specify the name of the executable for a headers provider plugin.

### --help

Display help for tctl in the CLI.

Alias: `-h`

### --namespace

Specify a Namespace.
By using this modifier, you don't need to specify a `--namespace` modifier for a sub-command.
The default Namespace is `default`.

Alias: `--n`

### --tls_ca_path

Specify the path to a server Certificate Authority (CA) certificate file.

### --tls_cert_path

Specify the path to a public X.509 certificate file for mutual TLS authentication.
If you use this modifier, you must also use the `--tls_key_path` modifier.

### --tls_disable_host_verification

Disable verification of the server certificate (and thus host verification).

### --tls_key_path

Specify the path to a private key file for mutual TLS authentication.
If you use this modifier, you must also use the `--tls_cert_path` modifier.

### --tls_server_name

Specify an override for the name of the target server that is used for TLS host verification.
The name must be one of the DNS names listed in the server TLS certificate.
Specifying this modifier also enables host verification.

### --version

Display the version of tctl in the CLI.

### --codec_endpoint

The URL and port number for a Codec Server.

## Environment variables

Setting environment variables for repeated parameters can shorten tctl commands.

### TEMPORAL_CLI_ADDRESS

Specify a host and port for the Frontend Service.
The default is `127.0.0.1:7233`.

### TEMPORAL_CLI_AUTHORIZATION_TOKEN

Specify a token to be used by the HTTP Basic Authorization plugin.

{/* TODO: Add link to "Securing tctl" page or its equivalent when it exists. */}

### TEMPORAL_CLI_AUTH

Specify the authorization header to be set for a gRPC request.

### TEMPORAL_CLI_NAMESPACE

Specify a Namespace.
By setting this variable, you don't need to specify a `--namespace` modifier in a tctl command.
The default Namespace is `default`.

### TEMPORAL_CLI_PLUGIN_DATA_CONVERTER

Specify the name of the executable for a custom Data Converter plugin.

### TEMPORAL_CLI_PLUGIN_HEADERS_PROVIDER

Specify the name of the executable for a headers provider plugin.

### TEMPORAL_CLI_TLS_CA

Specify the path to a server Certificate Authority (CA) certificate file.

### TEMPORAL_CLI_TLS_CERT

Specify the path to a public X.509 certificate file for mutual TLS authentication.

### TEMPORAL_CLI_TLS_DISABLE_HOST_VERIFICATION

Set to disable verification of the server certificate (and thus host verification).

### TEMPORAL_CLI_TLS_KEY

Specify the path to a private key file for mutual TLS authentication.
If you set this variable, you must also set the `TEMPORAL_CLI_TLS_CERT` variable.

### TEMPORAL_CLI_TLS_SERVER_NAME

Specify an override for the name of the target server that is used for TLS host verification.
The name must be one of the DNS names listed in the server TLS certificate.
Setting this variable also enables host verification.

### TEMPORAL_CONTEXT_TIMEOUT

Specify a timeout for the context of an RPC call in seconds.
The default value is 5.
